home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 1.iso / ARGONET / PD / FILER / X-FILESRC.ZIP / xrecover / Read me < prev    next >
Text File  |  1997-01-08  |  11KB  |  249 lines
  1.                                 X-RECOVER 0·09
  2.  
  3. A program to attempt recovery of an x-file's contents
  4.  
  5.    X-Files is an image filing system written by Andy Armstrong. Normal
  6.    (filecore based) Risc OS filing systems are limited to 10 character
  7.    leafnames and 77 files per directory. X-Files supports long
  8.    filenames (up to 256 characters internally) and an unlimited number
  9.    of files per directory, storing files in an x-file (which in other
  10.    respects behaves like a "normal" directory).
  11.  
  12.    Unfortunately X-Files is not totally robust, and can occasionally
  13.    corrupt an x-file, which it will then refuse to open. Sod's law
  14.    ensures that the data in the x-file is very important and not
  15.    backed up anywhere else. This is where x-recover comes in;
  16.    x-recover will _attempt_ to make sense of and extract data from
  17.    corrupted x-files.
  18.  
  19. Important: x-recover comes with absolutely NO WARRANTY
  20.  
  21.    This program is distributed in the hope that it will be useful, but
  22.    without any warranty; without even the implied warranty of
  23.    merchantability or fitness for a particular purpose. As x-recover
  24.    is written in C it almost certainly breaks the rules somewhere, and
  25.    hence is exhibiting "undefined behaviour". What this means in
  26.    English is that it could do anything at all, including, but not
  27.    limited to:
  28.  
  29.      1. Working exactly as intended
  30.      2. Trashing your hard disc
  31.      3. Turning Barbara Cartland into a goth*
  32.  
  33.   Usage
  34.  
  35.    x-recover [options] <x-file> <destination>
  36.  
  37.    x-file is the pathname of the x-file to attempt to recover.
  38.    x-recover does not check the filetype (so if x-file is not actually
  39.    an x-file x-recover will generate copious warnings as it discovers
  40.    this).
  41.  
  42.    destination is the pathname a directory (or empty x-file) to write
  43.    recovered contents into. destination should exist, or use the -c
  44.    option to create a new x-file with this name. destination can be
  45.    omitted if file output is suppressed (-g or -n options).
  46.  
  47.   Options
  48.  
  49.    -a  extract the full chunk allocated to the file, rather than the
  50.        length used. Using this option causes the chunktable to be
  51.        written out.
  52.  
  53.    -c  create destination as an x-file if no directory/x-file of this
  54.        name exists.
  55.  
  56.    -d  Output probable _d_irectories in raw binary form. See
  57.        directories.
  58.  
  59.    -f  write out any free space between chunks. x-recover -a -d -f -1
  60.        will output the entire x-file split into chunks, which if
  61.        concatenated in numerical order will give the original x-file.
  62.        [see size]
  63.  
  64.    -g  guess the location of the chunktable and the root directory.
  65.        x-recover simply runs through the file looking areas that
  66.        resemble the chunktable and the root directory. When used with
  67.        the -r and -t options this allows recovery even when the file
  68.        header is corrupted. This option suppresses all disc output.
  69.  
  70.    -n  no disc output. Integrity checks and errors are still reported
  71.        to the screen.
  72.  
  73.    -r  <offset>specify the offset of the root directory in x-file.
  74.        Useful if the header becomes corrupted - see header.
  75.  
  76.    -s  suppress file output, but still create the directories (and
  77.        free space) in destination. Mostly used for development
  78.        purposes to quickly check that things are working without
  79.        having to wait while files are copied, but x-recover -1 -f -s
  80.        will only extract directories and free space between
  81.        directories.
  82.  
  83.    -t  <offset>specify the offset of the chunktable in x-file. Useful if
  84.        the header becomes corrupted - see header.
  85.  
  86.    -v  verbose info. x-recover prints out more information about what it
  87.        is doing. Use more vs for more verbosity. -1Use Method 1 to attempt
  88.        to recover x-file's contents. The various methods are described
  89.        below.
  90.  
  91.    -2  Use Method 2 to attempt to recover x-file's contents. Method 2 is
  92.        the current default.
  93.  
  94.   The x-file structure, and how this affects the prognosis
  95.  
  96.    As the x-file file contains within itself data from other files, it
  97.    must also store information about the contained files and their
  98.    data. If an x-file becomes corrupted, it is likely that some of
  99.    this housekeeping information is lost. The x-file structure is
  100.    described here - which parts survive determines if recovery is
  101.    possible, and if so the fidelity achievable.
  102.  
  103.    Header
  104.  
  105.    An x-file starts with a header which contains a signature, version
  106.    information and pointers to the chunktable and root directory. If
  107.    the information stored in the header becomes corrupted it is
  108.    possible to search for the chunktable using the -g option.
  109.  
  110.    Chunktable
  111.  
  112.    Except for the header all information in the x-file is stored in
  113.    chunks. The index containing chunk sizes and positions is stored in
  114.    the chunktable - clearly if the chunktable is missing then the
  115.    x-file is simply an amorphous lump of data (like a corrupt hard
  116.    disc). Currently x-recover doesn't have the knowledge to identify
  117.    files from inspection of contents, so if the chunktable is missing
  118.    automated recovery is not possible as x-recover cannot determine
  119.    where one file stops and the next starts. If the chunktable is
  120.    reasonably intact then Method 1 can be used to extract the contents
  121.    of each chunk as separate files, but all name, filetype and
  122.    datestamp information will be lost.
  123.  
  124.    Root Directory
  125.  
  126.    Information about names, filetypes, attributes and modification
  127.    time is stored in the root directory and its subdirectories. If the
  128.    root directory can be found (either from the header or using the -g
  129.    option) then Method 2 can be used to attempt recovery of the
  130.    x-file's contents and directory structure, including file type
  131.    information.
  132.  
  133.   Method 1
  134.  
  135.    Method 1 reads in the chunktable, and then systematically writes
  136.    out the contents of each non-free chunk as a file the destination
  137.    directory/x-file. If it suspects that the chunk represents a
  138.    directory it writes a text file describing the directory's
  139.    contents, else it copies out the raw contents with filetype Data
  140.    (FFD). All chunks can be copied out as raw contents with the -d
  141.    option. Files and directories are named as file0000 file0001 etc in
  142.    the order that they are found in the x-file body (probably not the
  143.    same order as chunktable - use -vv (very verbose) or greater to
  144.    list the chunktable).
  145.  
  146.   Method 2
  147.  
  148.    Method 2 reads in the chunktable and the root directory. Starting
  149.    in the root directory it attempts to create a list of all files,
  150.    their filetype, attributes, and location within the x-file
  151.    (obtained via the chunktable). It recreates this directory
  152.    structure within the destination directory/x-file, and then copies
  153.    out all the files it found with their correct filenames, restoring
  154.    filetypes, access attributes and modification times. It then tries
  155.    to tally files that it knows exist but has no location with
  156.    un-recovered chunks from the chunktable, and writes out any
  157.    successful matches to the destination. Finally it writes the
  158.    contents of any remaining unrecovered chunks as files in the
  159.    destination using Method 1. Well, that's the plan...
  160.  
  161.     Directories
  162.  
  163.    Like the normal Risc OS filing system, X-Files writes a special
  164.    signature at the start of all directories so that when it reads the
  165.    chunk containing the directory information, it can check that the
  166.    information is not corrupted. X-Files' signature is the string Andy
  167.    at the start of the chunk. Hence, if x-recover comes across a chunk
  168.    about which it has no information, it will have a look for this
  169.    signature. If present, the chunk is assumed to be a directory,
  170.    which means that there is a small chance that a file which starts
  171.    with the text "Andy" will interpreted as a directory and
  172.    consequently garbled. If this happens, use the -d option to disable
  173.    directory identification, and the file contents will be recovered
  174.    intact.
  175.  
  176.     Size
  177.  
  178.    Size of a file is stored _twice_ in an x-file:
  179.  
  180.     1. The directory stores the size of a file
  181.     2. The chunktable stores the size of a chunk
  182.  
  183.    As the directory also stores an index into the chunktable, it is
  184.    possible to have conflicting sizes reported for a given file. In
  185.    this case x-recover will use the larger of the size in the
  186.    directory and the size in chunktable. This could cause the
  187.    recovered file to acquire a copy of the start of the next chunk,
  188.    which can mean that _the sum of the sizes of the recovered parts is
  189.    greater than the size of the x-file_. You don't get any extra
  190.    information - you just get some of it twice!
  191.  
  192.   Bugs
  193.  
  194.    We don't do bugs.
  195.  
  196.    None known - everything works to the design. However, there are
  197.    known design deficiencies (and planned improvements). Please report
  198.    bugs (preferably with fixes) to <bagpuss@done.net>. If you can
  199.    supply an x-file to demonstrate then this would be useful.
  200.    Currently I'm quite happy for relevant e-mail up to 1Mb, but if
  201.    bagpuss.done.net is up then use anonymous ftp to upload problem
  202.    files to ftp://bagpuss.done.net/
  203.  
  204.    Files up to 100Mb are acceptable by this method. No, I'm not
  205.    confusing Kb with Mb. If you're on Janet then you should be able to
  206.    shift 100Mb to me in 7 minutes.
  207.  
  208.     Design deficiencies
  209.  
  210.    Unrecovered chunks are written out as file#### in the destination
  211.    directory/x-file _after_ files are recovered, overwriting any
  212.    genuine files with the same name(s). Of course, no-one names files
  213.    like this... (So if you recover one x-file into another rename
  214.    these files rapidly.)
  215.  
  216.    The file#### naming system assumes that you have less than 10000
  217.    chunks. If this is violated x-recover will probably crash from
  218.    undefined behaviour as several internal buffers overflow. Don't say
  219.    that I didn't warn you - this software comes with absolutely no
  220.    warranty.
  221.  
  222.    Method 2 doesn't re-attach subdirectories (and hence cannot recover
  223.    name/date/attribute information for files contained in these
  224.    directories). The chunks are recovered by Method 1. I can't just
  225.    stick them in the destination directory/x-file in case two names
  226.    clash, as the second will overwrite the first. Method 3 (when
  227.    written (when someone asks me to)) will hook unclaimed directories
  228.    into the correct parent (with names like dir_0000 ).
  229.  
  230.    Likewise, Method 2 (and 3) ignore entries in the dirhash that don't
  231.    correlate with full filenames. Consider what would happen with two
  232.    files _aard_vark and _aard_wolf...
  233.  
  234.     Don't be caught out by
  235.  
  236.    Method 2 restores file permissions (where known). If it restores a
  237.    file as LR/ (no write access) and an attempt is made to recover the
  238.    x-file to the same directory, x-recover will not be able to open
  239.    the file again, so will recover the contents as a Method 1
  240.    unrecovered chunk.
  241.  
  242.    * Black is a much nicer colour than pink
  243.      _________________________________________________________________
  244.  
  245.  
  246.  
  247.    This document was last reviewed on Wednesday November 6th 1996
  248.    Nicholas Clark <Nicholas.Clark@Liverpool.ac.uk>
  249.